<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.9.1"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>FLAC: Porting from FLAC 1.3.4 to 1.4.0</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname">FLAC
   &#160;<span id="projectnumber">1.4.3</span>
   </div>
   <div id="projectbrief">Free Lossless Audio Codec</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.1 -->
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
$(function() {
  initMenu('',false,false,'search.php','Search');
});
/* @license-end */</script>
<div id="main-nav"></div>
</div><!-- top -->
<div class="header">
  <div class="headertitle">
<div class="title">Porting from FLAC 1.3.4 to 1.4.0<div class="ingroups"><a class="el" href="group__porting.html">Porting Guide for New Versions</a></div></div>  </div>
</div><!--header-->
<div class="contents">
<p>This module describes porting from FLAC 1.3.4 to FLAC 1.4.0. </p>
<h1><a class="anchor" id="porting_1_3_4_to_1_4_0_summary"></a>
Summary</h1>
<p>Between FLAC 1.3.4 and FLAC 1.4.0, there have four breaking changes</p><ul>
<li>the function get_client_data_from_decoder has been renamed to FLAC__get_decoder_client_data</li>
<li>some data types in the <a class="el" href="structFLAC____Frame.html">FLAC__Frame</a> struct have changed</li>
<li>all functions resizing metadata blocks now return the object untouched if memory allocation fails, whereas previously the handling varied and was more or less undefined</li>
<li>all functions accepting a filename now take UTF-8 encoded filenames on Windows instead of filenames in the current codepage</li>
</ul>
<p>Furthermore, there have been the following additions</p><ul>
<li>the functions FLAC__stream_encoder_set_limit_min_bitrate, FLAC__stream_encoder_get_limit_min_bitrate, FLAC::encoder::file::set_limit_min_bitrate() and FLAC::encoder::file::get_limit_min_bitrate() have been added</li>
<li>Added FLAC__STREAM_DECODER_ERROR_STATUS_BAD_METADATA to the FLAC__StreamDecoderErrorStatus enum</li>
</ul>
<h1><a class="anchor" id="porting_1_3_4_to_1_4_0_breaking"></a>
Breaking changes</h1>
<p>The function <b>get_client_data_from_decoder</b> was added in FLAC 1.3.3 but did not follow the API naming convention and was not properly exported. The function is now renamed and properly integrated as FLAC__stream_decoder_get_client_data</p>
<p>To accomodate encoding and decoding 32-bit int PCM, some data types in the <b>FLAC__frame</b> struct were changed. Specifically, warmup in both the <a class="el" href="structFLAC____Subframe__Fixed.html">FLAC__Subframe_Fixed</a> struc and the <a class="el" href="structFLAC____Subframe__LPC.html">FLAC__Subframe_LPC</a> struct is changed from FLAC__int32 to FLAC__int64. Also, value in the <a class="el" href="structFLAC____Subframe__Constant.html">FLAC__Subframe_Constant</a> is changed from FLAC__int32 to FLAC__int64. Finally, in <a class="el" href="structFLAC____Subframe__Verbatim.html">FLAC__Subframe_Verbatim</a> struct data is changes from a FLAC__int32 array to a union containing a FLAC__int32 array and a FLAC__int64 array. Also, a new member is added, data_type, which clarifies whether the FLAC__int32 or FLAC__int64 array is in use.</p>
<p>Furthermore, the following functions now return the object untouched if memory allocation fails, whereas previously the handling varied and was more or less undefined</p>
<ul>
<li>FLAC__metadata_object_seektable_resize_points</li>
<li>FLAC__metadata_object_vorbiscomment_resize_comments</li>
<li>FLAC__metadata_object_cuesheet_track_resize_indices</li>
<li>FLAC__metadata_object_cuesheet_resize_tracks</li>
</ul>
<p>The last breaking change is that all API functions taking a filename as an argument now, on Windows, must be supplied with that filename in the UTF-8 character encoding instead of using the current code page. libFLAC internally translates these UTF-8 encoded filenames to an appropriate representation to use with _wfopen. On all other systems, filename is passed to fopen without any translation, as it in libFLAC 1.3.4 and earlier.</p>
<h1><a class="anchor" id="porting_1_3_4_to_1_4_0_additions"></a>
Additions</h1>
<p>To aid in creating properly streamable FLAC files, a set of functions was added to make it possible to enfore a minimum bitrate to files created through libFLAC's <a class="el" href="stream__encoder_8h.html" title="This module contains the functions which implement the stream encoder.">stream_encoder.h</a> interface. With this function enabled the resulting FLAC files have a minimum bitrate of 1bit/sample independent of the number of channels, i.e. 48kbit/s for 48kHz. This can be beneficial for streaming, as very low bitrates for silent sections compressed with 'constant' subframes can result in a bitrate of 1kbit/s, creating problems with clients that aren't aware of this possibility and buffer too much data.</p>
<p>Finally, FLAC__STREAM_DECODER_ERROR_STATUS_BAD_METADATA was added to the FLAC__StreamDecoderErrorStatus enum to signal that the decoder encountered unreadable metadata. </p>
</div><!-- contents -->

<hr size="1"/>
Copyright (c) 2000-2009  Josh Coalson
Copyright (c) 2011-2023  Xiph.Org Foundation
<!-- Copyright (c) 2000-2009  Josh Coalson -->
<!-- Copyright (c) 2011-2023  Xiph.Org Foundation -->
<!-- Permission is granted to copy, distribute and/or modify this document -->
<!-- under the terms of the GNU Free Documentation License, Version 1.1 -->
<!-- or any later version published by the Free Software Foundation; -->
<!-- with no invariant sections. -->
<!-- A copy of the license can be found at http://www.gnu.org/copyleft/fdl.html -->
</body>
</html>
